feat: add Lambda SnapStart support - #831

hook_target returned Ok(None) for a configured path that canonicalizes to the
root ("/", "//", "/..", "/.", "/foo/..", "/%2f"), silently disabling the guard.
But after_restore POSTs the RAW configured path — it reads after_restore_path,
not the guard target — so the hook still fired at "/". The two diverged with no
diagnostic: with AWS_LWA_SNAPSTART_AFTER_RESTORE_PATH=/.. the adapter POSTs to
"/" on every restore, which is a 405 on both FastAPI examples (they declare only
`@app.get("/")`), and post_hook treats any non-2xx as fatal — so every restore
failed and nothing explained why.

Reject it instead. The guard cannot cover the root without returning 403 for all
normal traffic, and the docs require a hook path "your normal application traffic
does not use", which the root never is. Same rule as the % cases: if the adapter
cannot guard the route, it refuses to run with it rather than starting up with a
state-mutating route reachable or a hook that fails every restore.

Unset and empty still mean "no hook" and are unaffected.

…r SnapStart

build_client applied pool_max_idle_per_host(0) whenever
AWS_LAMBDA_INITIALIZATION_TYPE=snap-start, and that variable stays set for the
whole lifetime of a restored environment. Both call sites went through it, so the
client rebuilt in after_restore -- the one Adapter::client() returns for every
invocation after a restore -- also never retained a connection. The configured
idle keep-alive was therefore a no-op on exactly the functions this feature
targets, and every invocation opened a fresh TCP connection to the inner app for
the life of the environment, consuming a file descriptor each time against
Lambda's limit.

The snapshot hazard only applies to the client built BEFORE the snapshot. A
client built inside after_restore starts with an empty pool and cannot hold a
snapshotted connection, so it is safe for it to pool normally.

build_client no longer reads the environment; the caller decides, so the
post-restore rebuild cannot silently inherit the pre-snapshot restriction.
Adapter::new passes Duration::ZERO under SnapStart via the new
base_client_idle_timeout, which disables idle keep-alive for the pre-snapshot
client -- measured equivalent to pool_max_idle_per_host(0), including for
back-to-back requests. The configured value is retained on
Adapter::pool_idle_timeout and used for the after-restore rebuild.

This keeps the pre-snapshot client safe by construction, so a consumer driving
the Service impl directly (who never triggers the after-restore hook) is still
protected against hyper#3810, and it removes the post-restore path's dependence
on AWS_LAMBDA_INITIALIZATION_TYPE.

Also makes the SnapStartHooks::pool_idle_timeout field comment true: the
post-restore client now really does honor the configured value.

…ness branch

Findings from a final systematic pass over the branch.

1. hook_target short-circuits on configured.is_empty() and returns Ok(None) ("no
   hook"), but Adapter::new stored the raw Some(""), which run() hands to
   SnapStartHooks. before_snapshot/after_restore then took their `if let
   Some(path)` branch and called post_hook(.., ""), and Url::set_path("") yields
   "/" -- so the adapter POSTed to the unguarded application root on every
   lifecycle event (405 on both FastAPI examples, which post_hook treats as
   fatal). This is the same guard-versus-POST divergence the root-collapse
   rejection closed; "" slipped past by returning before canonicalization.
   Adapter::new now normalizes an empty hook path to None before anything reads
   it, so both sides agree by construction and the documented "empty means unset"
   semantics are preserved. Only reachable via a directly constructed
   AdapterOptions -- env-derived options already drop empties.

2. readiness::wait_until_ready drives Retry::spawn over an unbounded
   FixedInterval, so it can only return ready or never return. Its bool, and the
   `if !ready` branches plus "readiness check failed" errors in
   check_readiness_with_timeout / check_readiness_unbounded, were unreachable.
   Removed; wait_until_ready now returns (). check_init_health's ready_at_init
   comes from whether the wait COMPLETED within its bound, which is what the
   value always meant. Documented that an unbounded post-restore wait holds the
   restore open until Lambda's own timeout, with the escalating "app is not ready
   after {}ms" log as the adapter-side signal, and that
   AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS converts that into /restore/error.

Doc corrections, no behavior change:

- canonicalize_hook_path's rustdoc listed a control/null byte as a None case, but
  control bytes are stripped and canonicalization continues -- they WIDEN the
  blocked class. Stale in the fail-open direction. The same paragraph still
  described the HookTarget::Raw fallback deleted in ca56fd9, and the guard
  comment in fetch_response repeated the control-byte claim.
- build_client / base_client_idle_timeout claimed Duration::ZERO means no
  connection is "retained". It does not: hyper's pool stays enabled
  (Config::is_enabled is max_idle_per_host > 0), so the socket is still parked and
  captured in the snapshot; ZERO guarantees it is evicted on checkout rather than
  reused. Documented the real guarantee, and the init-time reconnect cost it
  carries (27 connections per 300ms of readiness polling versus 1) -- confined to
  init, and unchanged from the pool_max_idle_per_host(0) behavior it replaced.
- SnapStartHooks::client is used for the before-checkpoint hook only;
  after_restore deliberately uses the fresh client.
- The guide's rejection rule said "a path containing a percent sign", stricter
  than the code, which rejects only when the DECODED form contains one --
  /snapstart/%61fter is accepted and guarded as /snapstart/after.
- Two public-docs-link-to-private-item rustdoc warnings; cargo doc --no-deps is
  now clean.
- Unused `import os` in the zip example.

…h; warn on bad env values

Three findings from the latest bot pass.

1. A hook path equal to AWS_LWA_PASS_THROUGH_PATH was accepted, but the
   pass-through rewrite in fetch_response replaces `path` with pass_through_path
   for a PassThrough POST BEFORE the guard runs. So configuring the hook at
   /events -- the default pass-through path -- made every non-HTTP trigger event
   canonicalize onto the guarded route and get a 403 instead of reaching the app,
   silently, with only a per-invocation warn!. Adapter::new now rejects a hook path
   that resolves to the same route as the pass-through path, alongside the existing
   unguardable cases, and compares canonical routes so /Events, /events/, /./events
   and /%65vents are caught too.

2. duration_secs_from_env silently fell back to the default on any unparseable
   value -- the exact failure mode readiness_check_timeout_from_env was written to
   avoid. The two sibling variables also accepted different numeric formats:
   AWS_LWA_READINESS_CHECK_TIMEOUT_SECONDS took fractional seconds while
   AWS_LWA_POOL_IDLE_TIMEOUT_SECONDS took only whole ones, so `0.5` and `4.5`
   parse-failed into 4s with no diagnostic. It now accepts fractional seconds like
   its sibling and warns on any set-but-unusable value.

3. The request path was canonicalized twice per invocation whenever both hook paths
   are configured -- the configuration both examples and the guide use -- because
   each matches_hook_path call canonicalized independently. New matches_any_hook_path
   canonicalizes once and compares against both targets; semantics are identical, and
   the no-hooks case still short-circuits before canonicalizing. matches_hook_path
   becomes the #[cfg(test)] single-target form.

The guide's rejection list gains the pass-through case, and Adapter::new's # Errors
section now names all four unguardable hook-path conditions.

Regression from de0ea31. The pass-through collision check ran

    let pass_through_target = hook_target(&domain, &Some(pass_through_path))?;

unconditionally, so a pass_through_path that hook_target rejects aborted
Adapter::new -- with a SnapStart-flavored error -- even when no hook was
configured and there was therefore no guard and nothing to collide with.
AWS_LWA_PASS_THROUGH_PATH is read straight from the environment with no prior
validation, and "/" is a plausible setting for an app that handles non-HTTP event
payloads at its root; it collapses to the root and so was rejected. The same
applied to a pass-through path whose decoded form contains a literal % or a
malformed escape. Existing tests missed it because they all use the default
/events, which canonicalizes cleanly.

The check now runs only when a hook target exists, and treats an unguardable
pass-through path as "no collision" rather than an error. That is sound, not just
lenient: hook targets are canonicalizable and non-empty by construction, so a
request rewritten onto a root-collapsing, %-bearing, or non-canonicalizable
pass-through path can never canonicalize onto one -- the guard would pass it
through anyway.

`let _ = self.restored_client.set(fresh.clone())` discarded the "already set"
case and then used `fresh` for steps 2 and 3. If the cell were already populated,
the hook POST and the readiness check would run over a client no request can
reach, so the restore would report healthy on the basis of something the request
path never touches -- with no signal anywhere.

New publish_or_adopt returns whichever client invocations will actually use:
`fresh` when it wins the race, otherwise the already-published one. That removes
the divergence rather than merely reporting it, and warns so an unexpected second
lifecycle run is visible in logs.

Latent today, since lambda_runtime drives the restore lifecycle once. The test
pins the property directly via Arc::ptr_eq -- a second call must return the first
client, not its own -- so it cannot become real.

register_extension_internal built its RAPID client with default pooling, so a
connection to the Runtime API could be parked in the idle pool and captured in a
SnapStart snapshot. That is the same hazard lambda_runtime handles by calling
reset_pool() on its own RAPID client during the restore lifecycle -- but nothing
resets or re-establishes this one, and register_default_extension terminates the
process with exit(1) when its request fails, so handing out a dead connection
after restore would kill the restored environment before it serves anything.

Pooling costs nothing to give up here: the client issues exactly two requests,
`register` and then the long poll for the first extension event, and the long
poll's in-flight connection is unaffected by the idle-pool setting. Disabled
unconditionally rather than gated on AWS_LAMBDA_INITIALIZATION_TYPE, since there
is no case where reuse helps.

Extracted as runtime_api_client so the property is testable; the test observes
connection lifetime (dropped vs parked), and I confirmed it fails against a
default-pooled client before the change.

The pre-PR comment explaining why pooling was disabled under SnapStart was the
only record of the reason, and it was deleted. Restore it with the measurement
that settles it, taken from a SnapStart container function deployed from this
branch:

  across the restore:  monotonic +0.54s   while wall +161s
  after the restore:   monotonic +6.079s / +6.059s  vs wall +6.1s / +6.0s

CLOCK_MONOTONIC does not advance across the snapshot gap, but never goes
backwards, and after the restore it tracks wall time exactly. So the anomaly is
confined to the boundary, which is what makes the two sites correct in opposite
directions:

- Adapter::new (pre-snapshot) must have the pool OFF. hyper decides reuse with
  `now.saturating_duration_since(idle_at) > idle_timeout`, so an entry pooled
  before the snapshot reads as ~0.5s idle after restore however long the snapshot
  sat -- fresh, and dead. No idle timeout fixes that, including Duration::ZERO,
  since ZERO > ZERO is false. This is hyper#3810 / rust-lang/rust#79462.

- after_restore may have the pool ON. Every entry it holds is post-boundary, where
  accounting is reliable; verified live with idle gaps longer than the configured
  4s keep-alive all succeeding. This is also the only way
  AWS_LWA_POOL_IDLE_TIMEOUT_SECONDS affects the invocations that serve traffic.

Comment-only; no behavior change.

…cation

The guard's summary line and a test-section banner called it "strict, fail-closed"
while the detailed doc a dozen lines below correctly explains that the REQUEST side
forwards an undecidable path rather than 403-ing it. Only the configured side fails
closed, and the review bot has now twice read the summary, concluded the request
side returns 403 on doubt, and re-raised it as a contradiction -- quoting doc text
that was already replaced.

The risk is not the confusion itself but the obvious "fix" it invites: turning the
request-side pass-through into a 403 would reinstate the /reports/100%25 false-403
regression that pass-through exists to prevent.

Both labels now state which half does which, the summary points at the reasoning
rather than summarizing it away, and the term is gone from the codebase entirely
(the remaining historical use in a test comment is reworded to "undecidable
branch").

Comment-only; no behavior change.

HOOK_TIMEOUT capped each hook POST at 60 seconds. It was not useful, and it could
cause the failure it was meant to prevent.

Lambda already bounds both phases -- the init budget for the before-checkpoint
hook, the function timeout for the after-restore hook -- so there was no unbounded
hang left for the adapter to guard. What the cap actually did was land wrong in
both directions:

- For the after-restore hook it was unreachable. The restore phase is bounded by
  the function timeout, which is 10s in both shipped examples and 3s by default, so
  Lambda always won the race and the operator never saw the adapter's message. Four
  docs nonetheless promised "taking longer than 60 seconds to respond fails the
  SnapStart phase".
- For the before-checkpoint hook it was reachable but harmful: a legitimate slow
  drain that Lambda's much larger init budget would have allowed got killed at 60s,
  failing the version publish.

A cap derived from the function timeout would be the defensible version, but Lambda
does not expose the timeout as an environment variable and there is no invocation
context during these phases to read a deadline from. The doc comment records that
so nobody goes looking.

post_hook_with_timeout collapses into post_hook, its timeout-injection test goes
away with the behavior, and the four doc claims are corrected to say the adapter
imposes no deadline and that the after-restore hook must fit inside the function
timeout. Non-2xx and transport failures still fail the phase, still covered by
before_snapshot_non_2xx_is_error and
after_restore_publishes_client_even_when_hook_fails.

The doc comments had grown to carry review history, measurements and repeated
explanation. Cut roughly 200 lines net, keeping the part that stops a wrong edit
and dropping the narrative -- the detail lives in git history where it belongs.

src/snapstart.rs is down from 125 to 80 comment lines, src/lib.rs from 1200 to
1039. No behavior or test changes; the same tests pass.